Skip to content

docs: deeper structural improvements#5

Merged
flaglint merged 1 commit into
mainfrom
docs/deeper-improvements
Jul 1, 2026
Merged

docs: deeper structural improvements#5
flaglint merged 1 commit into
mainfrom
docs/deeper-improvements

Conversation

@Krishan27

@Krishan27 Krishan27 commented Jul 1, 2026

Copy link
Copy Markdown
Collaborator

Summary

Deeper structural improvements from the expert docs audit — expands thin pages, merges duplicates, and adds missing reference content.

Exit codes — merged duplicate pages

  • cli/exit-codes.md is now the complete authoritative page: full table (0/1/2/3/130), per-command matrix, CI YAML example, stability guarantee
  • reference/exit-codes.md deleted (was a duplicate)
  • Note: sidebar entry for reference/exit-codes needs removing (follow-up)

How FlagLint works — major expansion

  • Added import-verified concept with concrete false-positive TypeScript example
  • Shows why a function named variation() from an animation library is never flagged
  • Three-phase pipeline explanation (Collect → Analyse → Report)

Troubleshooting — 4 items → 9 items

Added: "0 flags detected", "Config file not found", "React patterns not auto-migrated", "--apply shows 0 transformed", "validate passes locally but fails in CI"

Report formats — full rewrite

  • Format comparison table (markdown/json/html/sarif/text × commands × best-for)
  • When-to-use prose for each format
  • GitHub Code Scanning SARIF upload example

openFeatureClientBindings — proper documentation

  • Explains variable-name semantics (not package name, not file path)
  • Multiple bindings example
  • Wrappers vs bindings distinction

Test plan

  • Build passes: 65 pages, 0 errors
  • how-flaglint-works.md renders false-positive code example
  • troubleshooting.md shows 9 items
  • report-formats.md shows comparison table and SARIF upload example
  • cli/exit-codes.md shows full table with per-command matrix
  • openFeatureClientBindings section in configuration.md is expanded

Summary by CodeRabbit

  • Documentation

    • Expanded CLI and concept guides with clearer usage examples, configuration details, supported formats, exit codes, and troubleshooting steps.
    • Added more guidance for migration, validation, and GitHub Actions workflows.
    • Clarified coverage limits and what is detected automatically versus for manual review.
  • Bug Fixes

    • Updated numerous documentation links to point to the current repository and page locations.

… report formats, exit codes, OF bindings

- Merge reference/exit-codes.md into cli/exit-codes.md: full table, per-command
  matrix, why-exit-1 explanation, CI YAML example, stability guarantee. Deleted
  the redundant reference page (sidebar update needed separately).
- Expand how-flaglint-works.md: import-verified concept with false-positive
  example, three-phase pipeline explanation, what FlagLint does not do.
- Expand troubleshooting.md: 4 items → 8 items covering 0-flags-detected,
  config-not-found, React-not-automigrated, apply-0-transformed, validate-CI-gap.
- Rewrite report-formats.md: format comparison table, when-to-use prose for each
  format, GitHub Code Scanning SARIF upload example.
- Expand configuration.md openFeatureClientBindings: what it does, example,
  multiple bindings, difference from wrappers.

Signed-off-by: Krishan Kant Sharma <krishansharma0327@gmail.com>
@coderabbitai

coderabbitai Bot commented Jul 1, 2026

Copy link
Copy Markdown

Review Change Stack

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 6420c854-449b-421b-91e3-23f442e983dc

📥 Commits

Reviewing files that changed from the base of the PR and between b147870 and 271bb1b.

📒 Files selected for processing (35)
  • src/content/docs/docs/cli/audit.md
  • src/content/docs/docs/cli/completion.md
  • src/content/docs/docs/cli/configuration.md
  • src/content/docs/docs/cli/exit-codes.md
  • src/content/docs/docs/cli/migrate.md
  • src/content/docs/docs/cli/report-formats.md
  • src/content/docs/docs/cli/scan.md
  • src/content/docs/docs/cli/validate.md
  • src/content/docs/docs/concepts/how-flaglint-works.md
  • src/content/docs/docs/concepts/openfeature-boundary.md
  • src/content/docs/docs/concepts/safety-model.md
  • src/content/docs/docs/concepts/source-level-debt-signals.md
  • src/content/docs/docs/enterprise-demo.md
  • src/content/docs/docs/guides/express.md
  • src/content/docs/docs/guides/manual-review-patterns.md
  • src/content/docs/docs/guides/monorepos.md
  • src/content/docs/docs/guides/nestjs.md
  • src/content/docs/docs/guides/troubleshooting.md
  • src/content/docs/docs/index.md
  • src/content/docs/docs/integrations/github-actions.md
  • src/content/docs/docs/integrations/openfeature-provider.md
  • src/content/docs/docs/integrations/opentelemetry.md
  • src/content/docs/docs/product-contract.md
  • src/content/docs/docs/quickstart.md
  • src/content/docs/docs/reference/changelog.md
  • src/content/docs/docs/reference/exit-codes.md
  • src/content/docs/docs/reference/faq.md
  • src/content/docs/docs/reference/limitations.md
  • src/content/docs/docs/reference/supported-scope.md
  • src/content/docs/docs/trust/security.md
  • src/content/docs/docs/tutorials/add-openfeature-provider.md
  • src/content/docs/docs/tutorials/enforce-in-github-actions.md
  • src/content/docs/docs/tutorials/migrate-a-node-service.md
  • src/content/docs/docs/tutorials/shared-client-architecture.md
  • src/content/docs/docs/why-flaglint.md

📝 Walkthrough

Walkthrough

This PR is a documentation-only update across the flaglint.dev docs site. It rewrites exit-code semantics, expands CLI configuration and report-format documentation, revises the analysis pipeline narrative, adds troubleshooting scenarios, updates command examples to npx flaglint@latest, and repoints "Edit this page on GitHub" links to the new flaglint.dev repository path.

Changes

Documentation content and link updates

Layer / File(s) Summary
Exit codes rewrite
src/content/docs/docs/cli/exit-codes.md, src/content/docs/docs/cli/scan.md, src/content/docs/docs/reference/exit-codes.md
Exit-codes.md gains expanded code tables, per-command notes, CI YAML examples, and stability guarantees; scan.md adds an explicit exit-codes table; the duplicate reference/exit-codes.md page is deleted.
Configuration and OpenFeature bindings
src/content/docs/docs/cli/configuration.md
Fields table adds type/default columns and stricter provider constraints; a new OpenFeature Client Bindings section clarifies migration output vs. wrapper detection.
Report formats expansion
src/content/docs/docs/cli/report-formats.md
Adds a format comparison table, updated SARIF/scan examples, GitHub Code Scanning workflow YAML, and revised migration report and footer navigation.
Concepts, scope, and quickstart clarifications
src/content/docs/docs/concepts/how-flaglint-works.md, src/content/docs/docs/index.md, src/content/docs/docs/reference/limitations.md, src/content/docs/docs/quickstart.md, src/content/docs/docs/integrations/github-actions.md
Rewrites analysis-pipeline narrative around import-verified detection, clarifies React SDK/browser provider scope, updates CLI examples to `npx flaglint@latest`, and documents a new `version` action input.
Troubleshooting guide expansion
src/content/docs/docs/guides/troubleshooting.md
Adds detailed sections covering SDK detection failures, config discovery, React SDK limits, migrate --apply skips, CI validation mismatches, and partial-migration validation failures.
Edit link repointing
src/content/docs/docs/cli/*, src/content/docs/docs/concepts/*, src/content/docs/docs/guides/*, src/content/docs/docs/integrations/*, src/content/docs/docs/reference/*, src/content/docs/docs/trust/security.md, src/content/docs/docs/tutorials/*, src/content/docs/docs/why-flaglint.md, src/content/docs/docs/enterprise-demo.md, src/content/docs/docs/product-contract.md
"Edit this page on GitHub" links across many pages are repointed from the legacy `flaglint/flaglint` docs-src path to the new `flaglint/flaglint.dev` src/content path.

Estimated code review effort: 2 (Simple) | ~15 minutes

Possibly related PRs

  • flaglint/flaglint.dev#3: Overlaps in editing src/content/docs/docs/cli/configuration.md (wrappers guidance) and src/content/docs/docs/cli/completion.md.

Poem

A rabbit hopped through docs anew,
Repointing links from old to new,
Exit codes gained a clearer voice,
Wrappers versus bindings — a wiser choice,
Troubleshooting grows, the guide's in view. 🐇📚

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/deeper-improvements

Comment @coderabbitai help to get the list of available commands.

@flaglint flaglint merged commit 271bb1b into main Jul 1, 2026
2 of 4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants